======================================================

	Blue ZX3's Road Runner Media Plugin

======================================================

	First, I'd like to give many thanks to JohnWPB for spending countless hours on helping me make this plugin 
	user friendy, giving ideas for features not thought of, the whole debugging process, and being intergrated
	into one of the best Road Runner skins around. Oh, and can't forget about dealing with my stubberness. :)
	
	This plugin gives Road Runner something that has been wanted by many for a long time.  It gives RR all the speed
	and feaures that all other database powered frontends have and then some.
	

General Info
------------

    Features:
    ---------
	Browse Modes: Artist, Album, Genre, Songs, Folders, Recently Added
		-Genre's also give you three sub choices of Artist,Albums,Songs from the selected Genre
	Sort list Modes: Title, Track, Artist, Album, Genre, Filename
	Fast song searches (Make that instant)!
	Search by: FileName, Title, Artist, Album, Genre, Year, Times a Song been played or All
	Song Rating's
	Builtin 10 Disk Changer, changer features for the changer include:
		- Play / Name / Rename / Clear/ Restart / any of the 10 disks
		- Add selected browse list item to a disk (good for adding media to a disk)	
		- Add or Replace contents of a disk with a saved Playlist
		- Auto resume to song and time when returning to a disk
		- Add/Remove Songs from a disk
		- Backup / Restore all disks
	Builtin 10 Virtual rotating playlist history (optional by setting)
	Top x played songs (user selectable!)
	Most x Recently played songs (user selectable!)
	Find recently added songs to the database
	TON'S of labels for just about any thing that you would want to be displayed...

	Only audio media now, but good chance that video too in near future...

    Notes:
    ------
	- Once the building or rescan of the database is started, it will be continued to untill is completed.  
	  Meaning if you reboot,shutdown, ect.. that the next time you startup RoadRunner, it will continue 
	  where it left off or was cut off.

	- At the end of the building, files that were missing one or more tags will be listed in a txt file in the RMDatabase folder 
	  called "Files Missing Tag Info.txt" and lists which tags were missing or could not be read

	- Rough build time on my Epia M10000 board in the car was about 5 Mins & 30 Secs having ~8.2k songs!


Installaton
-----------

	#1 Place the "RRMediaDb.dll" file be in the Road Runner folder and registered, along with Placing a "X,RRMediaDb" line in the "Menu.skin" file
	#2 The RMDatabase folder and all of its contents be placed in the Road Runner folder having the below minimal listed files
	   	In the '..\Road Runner\RMDatabase folder:
			RMBuilder.exe
			RRMediaDb.exe
			This File
		
	   	In the '..\Road Runner\RMDatabase\Support Files' folder:
			Sqlite3.exe
			Cddbcontrol.dll
			MediaInfo.dll
			Sqlite3u.dll
			Check.pn_
			Not.pn_
			Working.pn_

	#4 The following files in the '..\Road Runner\RMDatabase\Support Files' folder be registered: cddbcontrol.dll & sqlite3u.dll
	#5 A "RM_ONSONGSTART" cmd needs to be in the "ONSONGSTART" Event in either RoadRunner's Main ExexTbl.ini file or the skins ExecTbl.ini

=======================================================





=======================
Required Skin File Names
=======================
RM_Media.skin (**MUST CONTAIN A CUSTOM LIST**)
RM_Builder.skin
RM_DiskChanger.skin
RM_Builder_Stats.skin (Menu Type)
RM_NumOSK.skin (Menu Type)

==================================
Other Screen suggested Names and Types
==================================

Menu Type:
----------
RM_ReScan_Stats.skin
RM_Playlist2Disk.skin
RM_Select2Disk.skin
RM_BrowseMode.skin
RM_ListSortBy.skin


Basic CMD's
============

"RR_Media"		-	Loads "RM_Media.skin" and tells plugin that you are viewing skin
				  Exception: If no db is found when the plugin is initialized, 
					     it will load the "RM_Builder.skin" until the db buiding is completed

"RM_Builder"		-	Loads "RM_builder.skin" so that user can start building the database and 
				also tells the builder app, if its running, to update the skin indicators

"RM_Exitbldr"		-	Tells the builder app that you are leaving the screen and not to update 
				any indcators until you return, use "RM_Exitbldr||Cancel" to go back the previous screen

"RM_Stats"		-	When the database is done being built, this loads the menu "RM_Builder_Stats.skin"
				which diplays things like total files imported, time took, and avg songs per min

"RM_Firstrun"		-	A custom command that gets executed after the first time the RM_Builder sceen is show, could be used to have an informitive 
				popup menu telling user that they need to build the database before being able to use any of powerfull features
				  NOTE: executing logic flow is the RM_Builder.skin is loaded then the "RM_Firstrun" gets executed ONLY once!
			               This value get stored in the skin.ini file, doesn't have to be there at startup, but will be written once this cmd is executed,
			                either deleting this line or setting it to true will allow it the cmd to be re-executed (RMFirstRun=False)

"Db_Complete"		-	A custom command that the builder will execute when the building of the database is complete,
				Could be used to trigger the loading of the RM_Builder_Stats.skin

"Db_Rescan_Complete"   	-	A custom command that the builder will execute when the rescanning of the users music path is complete.
				Could be used to trigger the loading of the RM_Rescan_Stats.skin

"RM_DiskChanger"		-	Loads "RM_DiskChanger.skin" so that user can start building the database and 
				  Exception: If no db is found when the plugin is initialized, 
					     it will load the "RM_Builder.skin" until the db buiding is completed

"RM_SvdLST"		-	Plays the previous playlist before the Media plugin loaded a new one
				  NOTE: If the virtual playlists are enabled this command will rotate through the last 10 playlists (newest to oldest)
				      Setting is in the RRMediadb.ini file in the support files folder under virtPL=(true/false)

"RM_SvdLST+"		-	Like the above command, but allows forward/reverse movement through the virtual playlists
"RM_SvdLST-"

"RM_Select"		-	Acts the same as the "SELECT" command in rr on an audio browser screen, but include's the logic for dealing with the virt PL's and Virt CD's

"RM_!Select"		-	Acts the same as the "!SELECT" command in rr on an audio brower screen, ie..selects but stays in the screen, and includes the needed logic for the VPL's &VCD's

"RM_Browse"		-	Acts the same as "BROWSE" command in rr on an audio browser screen, double clicking on the list also does this
				NOTE:  when user is at a song level in the list, this cmd will act like rr's "ADD1"

"RM_Back"		-	Acts the same as "BACK" command in rr on an audio browser screen, ie one browse step back

"RM_Home"		-	Loads the list with the Home View, this is also the one that on the first time viewing the screen gets loaded

"RM_Add1"		-	Adds Item selected in list to the current playlist

"RM_PlayAlbum"		-	Plays full album in trach order depending on what level the list is at (Track tag must be correctly set)
				  IE..if you are at a songs/file level in the list it will play the full album of whatever is selected, otherwise
				  it will play the full album of whatever is currenly playing

"RM_MostPlayed"		-	Loads a playlist that contains the top played songs in decending order
				  NOTE: CMD polls the "RMSONGLIMIT" label in RR to set the limit of returned songs, if nothing is defined, it default's to 100

"RM_MostRecent"		-	Loads a playlist that contains the most recent played songs to the least played songs
				  NOTE: CMD polls the "RMSONGLIMIT" label in RR to set the limit of returned songs, if nothing is defined, it default's to 100

"RM_RecentlyAdded"	-	Creates a listing of the most recenly added media, sorted by either Artist,Album,Songs

"RM_LoadstarX"		-	Loads X star songs into playlist where X is the wanted rating (1 - 5)

"RM_RateX"		-	Applys the x rating to the song in the database where the x is the wanted rating (0-5)
				  NOTE: To remove the rating use "RM_Rate0"

"RM_RatedX"		-	This CMD sets the rating indicators where X is the rating (1 - 5)
				  NOTE: The only place these should really be located is in the RRMediaDb.ini in the support files folder under the rating heading

"RM_BuildDb"		-	Starts the database building app in the background with a LOW priority, as to not interfear with system performance

"RM_ResetPlayCount"	-	Resets all songs in database to a zero playcount

"RM_!PLSelect"		-	Same as the !Select cmd on a playlist screen, execpt that this has the needed logic to unload a disk if you have one loaded or save the current pl to a virtpl if turned on

"RM_PLSelect"		-	Same as the Select cmd on a playlist screen, execpt that this has the needed logic to unload a disk if you have one loaded or save the current pl to a virtpl if turned on

"RM_DLSelect"		-	Same as the Select cmd on a regular audio browse screen, execpt that this has the needed logic to unload a disk if you have one loaded or save the current pl to a virtpl if turned on

"RM_!DLSelect"		-	Same as the !Select cmd on a regular audio browse screen, execpt that this has the needed logic to unload a disk if you have one loaded or save the current pl to a virtpl if turned on

"RM_SongDateUSA"	-	Sets the RM_LastplayedDate label to MM/DD/YY format

"RM_SongDateDefault"	-	Sets the RM_LastplayedDate label to DD/MM/YY format

"RM_SkipTo"		-	This is simular to the "SkipTo;x" RR Cmd execpt that you can use on a Mini OSK type screen and will jump to the closest matched list item of what you typed in
				NOTE: The menu screen that this cmd is placed on needs to have a text box and includes an "ESC" cmd to close the menu screen



RM List Cmd's
=============
NOTE: FOLLOWING CMD'S NEED TO BE ON THE "RM_Media.skin" screen
      (or if used on a menu screen then use "CANCEL||RM_xxx")

"RM_Folder"	 	-	Loads the list with the MusicPath folders

"RM_Artist"		-	Loads the list with ALL Artists in database

"RM_Album"		-	Loads the list with ALL Albums in database

"RM_Genre"		-	Loads the list with ALL Genre's in database

"RM_Songs"		-	Loads the list with ALL Songs in database, displays "Querying DB...  One Moment Please" in the list while list is being built

"RM_RecentlyAdded"	-	Loads the list with time delimited intervals of when items where added, 
					ie.. < 1 Day,< 1 Week, < 2 Weeks,< 1 Month, < 2 Months, < 6 Months, < 1 Year.
					Then by Artist/Album/Songs.

"RM_Rating"		-	Loads the list with the selections: Un rated Songs,1-5 Stars,All Rated songs to browse by

"RM_Recent"		-	Loads the list with the most recently played songs order by most recent to least recent
				NOTE: This is just like the "RM_MostRecent" direct action cmd above but only loads the list w/o playing it
				  

RM_Home Setting Cmd's
=====================

"RM_SHFolder"	 	-	Sets the "RM_Home" to the MusicPath folders

"RM_SHArtist"		-	Sets the "RM_Home" to ALL Artists in database

"RM_SHAlbum"		-	Sets the "RM_Home" to ALL Albums in database

"RM_SHGenre"		-	Sets the "RM_Home" to ALL Genre's in database

"RM_SHSongs"		-	Sets the "RM_Home" to ALL Songs in database


List Sorting Cmd's
==================

"RM_Sortby"		-	This toggles through the list sortby methods when its time to make a On-the-fly playlist
				  The only time this and the cmds below reorganize the list is when its at a file/song level.
					NOTE: Sets the "RM_ListOrder" label to current list order, there are also 
					direct button commands for each sortby action, see below

"RM_SortbyTitle"
"RM_SortbyTrack"
"RM_SortbyFile"
"RM_SortbyArtist"	-	Direct button commands for the list sorting at a file or song level in the list and also used when making the new playlist
"RM_SortbyRandom"
"RM_SortbyAlbum"
"RM_SortbyGenre"


Db Search Cmd's
===============
Search note: The search resuls are shown in the list along with creating a [SearchResults].m3u playist in the 
	     users playlist path to be able to either play the entire search results or to put it on a virt disk


"RM_SrchDB"		-	Loads the OSK to enter search criteria and then diplays the results Using a 'Title(or filename if no title tag set) - Artist' format
				  NOTE: This search cmd will search in all catagories. ie...Artist,Album,Title,FIleName, ect...
			        	Distinct button commands are also availble to only search in one catagory, see below
"RM_SrchFilename"
"RM_SrchTitle"
"RM_SrchArtist"
"RM_SrchAlbum"		-	Commands for only searching in the command criteria
"RM_SrchGenre"			NOTE: The "RM_SrchYear" & "RM_SrchXPlayed" use a seperate numosk skin called "RM_NumOSK.skin"
"RM_SrchYear"			      using these two search modes you could do a search for songs played >3 or where Year <2000
"RM_SrchXPlayed"

"RM_Enter_2"		-	Used on the RM_NumOsk.skin as the enter button code	


Virtual CD Changer Cmd's
=========================

"RM_DiskX"		-	Loads disk number x, where x is the disk number ( 1- 10 )

"RM_SetDiskName"	-	Loads the OSK to enter a name for the currenly loaded disk

"RM_SetDiskName;X"	-	Like the above command but will set a disk's name where X is the disk number ( 1- 10 )

"RM_Disk-"		-	Load Previous disk, if at disk 1, will load disk 10

"RM_Disk+"		-	Load Next Disk, if at disk 10, will load disk 1

"RM_ClearDiskX"		-	Clears the X Disk, and set the Disk name to "Disk X" ( 1- 10 )

"RM_ReStartDiskX"	_	Restarts the X disk, updates the database disk resume info back to track 1 time 00:00, and if you have the same disk loaded,
				starts playing back at track 1

"RM_DiskBackup"		-	This command will backup up the disk names and the contents of each disk

"RM_DiskRestore"	-	This Command will use the backuped disks to restore disk names and all disk contents				
				NOTE: This WILL overwrite the current disk names and all disk contents
				******

"RM_Playlist2Disk"	-	Used in a playlist select screen to load the selected playlist into a disk and also allows you to name the selected disk					
				NOTE: flow of this cmd is: selects selected playlist > executes a custom RM command "RM_PLList2Disk" 
					(typically to load a menu scrn to pick which disk to select, using any combination of the 3 cmds below )
				*****

"RM_SetPLDiskX"		-	Used in conjunction with the above cmds to specify which disk to use, where X is the disk number (1 - 10)
				NOTE: typically used btn code would be "ESC||RM_SetPLDisk7", exit the above menu and set selected disk as loaded,
				      you can also use the below cmds to give more control over how the playlist is placed on the disk, if either
				      cmd below is not used, by default it will replace the contents of the selected disk

"RM_PL2DiskAdd"		-	This will set the the currently selected playlist to be added to the selected disk, and if its currently loaded, adds that playlist to to the playing now playlist
				NOTE: this command should be used as follows "RM_PL2DiskAdd||RM_SetPLDiskX" where X is the selected disk (1 - 10),
				      this cmd does not execute anything if used alone, just sets an internal flag

"RM_PL2DiskRepl"	-	This will set the the contents of the selected playist to replace the selected disk contents and sets the disk name 
				to the playlist's name, and if its currently loaded, adds that playlist to to the playing now playlist
				NOTE: this command should be used as follows "RM_PL2DiskRepl||RM_SetPLDiskX" where X is the selected disk (1 - 10),
				      this cmd does not execute anything if used alone, just sets an internal flag

"RM_Add2Diskx"		-	This will add the currently playing song to the x disk ( 1 - 10 )

"RM_ClearDiskx"		-	This will clear the x disk contents and resets the disk name to "Disk x" ( 1 - 10 )

"RM_Sel2Disk"		-	This grabs selected list item info then executes a custom "RM_Sel2DiskCMD" command that allows you 
				to specify how you want to load a screen to select which disk the list item is placed on
				NOTE: typical usage would be a menu style screen, and the custom command would be
				      "RM_Sel2DiskCMD","Menu;Sel2Disk.skin" on which the following commands would be placed

"RM_Select2Diskx"	-	Used inconjunction with the above command to select the x ( 1 - 10 ) disk for selected item to be placed on.

"RM_DiskRemoveSong"	-	This acts like the "Minus1" RR cmd and if a disk is also loaded, will remove the song from the current disk


LABEL CODES
============

"RM_TotalRecords"	-	Songs in database

"RM_LastPlayedDate"	-	Shows the last date when the song was played. To change format use the "RM_SetSongDatexxx" cmd above

"RM_PlayedCount"	-	Shows how many time song has been played

"RM_SongDateAdded"	-	Shows when the song was added to the database. To change format use the "RM_SetSongDatexxx" cmd above

"RM_DiskName"		-	Currently loaded disk name in the CD changer, if no disk loaded then label sets to "No Disk"

"RM_DiskNumber"		-	Currently loaded disk Number, if no disk loaded then label sets to "--"

"RM_DiskxName"		-	Name of Disk, where X is the disk # (1-10)

"RM_DiskxCount"		-	Number of Tracks on Disk x, where X is the disk # (1-10)

"RM_VirtPLPos"		-	If Virtual Playlist is turned on then this the current virtpl niumber that you are on

"RM_StarPLStatus"	-	Used in combination with the star playlist creation cmds, to tell you if no songs match selected cmd

"RM_ListOrder"		-	Is the current way of how the playlist is created or if at a song/file level in the media screen the way the list will be displayed

"RM_Media_Mode"		-	Shows what the current browsing by mode is, ie...folders,files/songs, artists, albums, genre's, ect...

"RM_SongLimit"		-	This shows the limit of songs that the "RM_MostPlayed","RM_MostRecent" cmds will return\play

"RM_BuildSongsAdded"	-	Shows the number of songs that were added after a database rescan is done

"RM_BuildSongsRemoved"  -	Shows the number of songs that were removed from the database because they no longer exits after a database rescan is done

"RM_BuildSongsUpdated"  -	Shows the number of song records that were updated when the database was rescaned, ie..user changed or updated some song tags

"RM_BuildStatus"	-	Shows what the builder is currently doing

"RM_BuildPercent"	-	Shows the Percentage of how far along the builder is in its current step, includes trailing percent sign

"RM_BuildCounter"	-	Shows the "done / out of" that goes with the percent label above

"RM_BuildFileCount"	-	Shows how many songs were imported on both the first scan and recan's

"RM_BuildTime"		-	Shows how long the build took.  ie.. "4 Minutes  34 Secs"

"RM_BuilderButton"	-	Shows what the builder will perform when the "RM_BuildDb" CMD is executed, 
				displays either "Build" if no database exsits or "Rescan" if database does exsists
	

Indicators
==========

"RM_DiskLoadedX"	-	Used to indicate which disk (Where X is 1-10) is currently loaded, fully automatic

"RM_DiskChangeRestore"	-	These indicate if either one of the disk backup/resotore cmds are being processed
"RM_DiskChangeBackup"

"RM_BuildStepx"		-	Shows both the step that the builder is on as well as the status of each completed step and currently working on step
				NOTE: There needs to be 4 png files in the skin folder that are used to diplay the status
				      The file names are as follows: RM_Working.png,RM_Complete.png,RM_Failed.png,RM_Skipped.png

"RM_xStar"		-	Shows the rating of the current song (where x is 1-5)
